.\" $Header$ -*-nroff-*-
.\" Purpose: ROFF man page for ncbo
.\" Usage:
.\" nroff -man ~/nco/man/ncbo.1 | less
.TH NCBO 1
.SH NAME
ncbo \- netCDF Binary Operator
.SH SYNTAX
ncbo [\-3] [\-4] [\-5] [\-6] [\-7] [\-A] [\-\-bfr
.IR sz_byt ] [\-C] [\-c] 
[\-\-cmp
.IR cmp_sng ]
[\-\-cnk_byt
.IR sz_byt ] [\-\-cnk_csh
.IR sz_byt ] [\-\-cnk_dmn 
.IR nm,sz_lmn ]
[\-\-cnk_map 
.IR map ]
[\-\-cnk_min
.IR sz_byt ]
[\-\-cnk_plc 
.IR plc ]
[\-\-cnk_scl 
.IR sz_lmn ] [\-D 
.IR dbg_lvl ]
[\-d 
.IR dim ,[
.IR min ][,[
.IR max ]]]
[-F] [--fl_fmt=fmt] [\-G
.IR gpe_dsc ]
[\-g  
.IR grp [,...]]
[\-\-gaa
.IR att_name=
.IR att_val ]]
[\-\-gad 
.IR att1 [,...]]
[\-H] [\-h] [\-\-hdf] [\-\-hdr_pad
.IR sz_byt ] [\-\-hpss_try]
[\-L 
.IR dfl_lvl ] 
[\-l 
.IR path ]
[\-\-msa] [\-\-no_cll_msr] [\-\-no_frm_trm] [\-\-no_tmp_fl] [\-O] [\-p 
.IR path ]
[\-\-qnt
.IR var1 [,
.IR var2 [,...]]=
.IR prc ]]
[\-\-qnt_alg
.IR alg_nm]
[\-R] [\-r] [\-\-ram_all] [\-t
.IR thr_nbr ]
[\-\-uio] [\-\-unn] [\-v 
.IR var [,...]]
[\-X 
.IR box ] 
[\-x] 
.I file_1
.I file_2
.I file_3
.SH DESCRIPTION
.PP
.B ncbo
subtracts variables in 
.I file_2
from the corresponding
variables (those with the same name) in 
.I file_1
and stores the
results in 
.IR file_3 .
Variables in 
.I file_2
are 
.I broadcast
to conform to the
corresponding variable in 
.I file_1
if necessary.  
Broadcasting a variable means creating data in non-existing dimensions
from the data in existing dimensions.
For example, a two dimensional variable in 
.I file_2
can be
subtracted from a four, three, or two (but not one or zero)
dimensional variable (of the same name) in 
.BR file_1 .
This functionality allows the user to compute anomalies from the mean.
Note that variables in 
.I file_1
are
.I not
broadcast to conform
to the dimensions in 
.IR file_2 .
Thus, 
.BR ncbo ,
the number of dimensions, or 
.IR rank ,
of any
processed variable in 
.I file_1
must be greater than or equal to the
rank of the same variable in 
.IR file_2 .
Furthermore, the size of all dimensions common to both 
.I file_1
and
.I file_2
must be equal. 
.PP
When computing anomalies from the mean it is often the case that
.I file_2
was created by applying an averaging operator to a file
with the same dimensions as 
.IR file_1 ,
if not 
.I file_1
itself.
In these cases, creating 
.I file_2
with 
.B ncra
rather than
.B ncwa
will cause the 
.B ncbo
operation to fail.
For concreteness say the record dimension in 
.B file_1
is
.BR time .
If 
.I file_2
were created by averaging 
.I file_1
over the
.B time
dimension with the 
.B ncra
operator rather than with the
.B ncwa
operator, then 
.I file_2
will have a 
.B time
dimension of size 1 rather than having no 
.B time
dimension at all 
In this case the input files to 
.BR ncbo ,
.I file_1
and
.IR file_2 ,
will have unequally sized 
.B time
dimensions which
causes 
.B ncbo
to fail.
To prevent this from occurring, use 
.B ncwa
to remove the 
.B time
dimension from 
.IR file_2 .
An example is given below.
.PP
.B ncbo
will never difference coordinate variables or variables of
type 
.B NC_CHAR
or 
.BR NC_BYTE .
This ensures that coordinates like (e.g., latitude and longitude) are
physically meaningful in the output file, 
.IR file_3 .
This behavior is hardcoded.
.B ncbo
applies special rules to some NCAR CSM fields (e.g.,
.BR ORO ).
See
.I "NCAR CSM Conventions
for a complete description.
Finally, we note that 
.B ncflint
(ncflint netCDF File
Interpolator) can be also perform file subtraction (as well as
addition, multiplication and interpolation). 
.PP
.SH EXAMPLES
.PP
Say files 
.B 85_0112.nc
and 
.B 86_0112.nc
each contain 12 months
of data.
Compute the change in the monthly averages from 1985 to 1986:
.RS
ncbo 86_0112.nc 85_0112.nc 86m85_0112.nc
.RE
.PP
The following examples demonstrate the broadcasting feature of
.BR ncbo .
Say we wish to compute the monthly anomalies of 
.B T
from the yearly
average of 
.B T
for the year 1985.
First we create the 1985 average from the monthly data, which is stored
with the record dimension 
.BR time .
.RS
ncra 85_0112.nc 85.nc
.br
ncwa \-O \-a time 85.nc 85.nc
.RE
The second command, 
.BR ncwa ,
gets rid of the 
.B time
dimension
of size 1 that 
.B ncra
left in 
.BR 85.nc .
Now none of the variables in 
.B 85.nc
has a 
.B time
dimension.
A quicker way to accomplish this is to use 
.B ncwa
from the
beginning:  
.RS
ncwa \-a time 85_0112.nc 85.nc
.RE
We are now ready to use 
.B ncbo
to compute the anomalies for 1985:
.RS
ncbo \-v T 85_0112.nc 85.nc t_anm_85_0112.nc
.RE
Each of the 12 records in 
.B t_anm_85_0112.nc
now contains the
monthly deviation of 
.B T
from the annual mean of 
.B T
for each
gridpoint. 
.PP
Say we wish to compute the monthly gridpoint anomalies from the zonal
annual mean. 
A 
.I "zonal mean"
is a quantity that has been averaged over the
longitudinal (or 
.IR x )
direction.
First we use 
.B ncwa
to average over longitudinal direction
.BR lon ,
creating 
.BR xavg_85.nc ,
the zonal mean of 
.BR 85.nc .
Then we use 
.B ncbo
to subtract the zonal annual means from the
monthly gridpoint data:
.RS
ncwa \-a lon 85.nc xavg_85.nc
.br
ncbo 85_0112.nc xavg_85.nc tx_anm_85_0112.nc
.RE
Assuming 
.B 85_0112.nc
has dimensions 
.B time
and 
.BR lon ,
this example only works if 
.B xavg_85.nc
has no 
.B time
or
.B lon
dimension.
.PP
As a final example, say we have five years of monthly data (i.e., 60 
months) stored in 
.B 8501_8912.nc
and we wish to create a file
which contains the twelve month seasonal cycle of the average monthly
anomaly from the five-year mean of this data. 
The following method is just one permutation of many which will
accomplish the same result.
First use 
.B ncwa
to create the file containing the five-year mean:
.RS
ncwa \-a time 8501_8912.nc 8589.nc
.RE
Next use 
.B ncbo
to create a file containing the difference of
each month's data from the five-year mean:
.RS
ncbo 8501_8912.nc 8589.nc t_anm_8501_8912.nc
.RE
Now use 
.B ncks
to group the five January anomalies together in one 
file, and use 
.B ncra
to create the average anomaly for all five
Januarys. 
These commands are embedded in a shell loop so they are repeated for all
twelve months:
.RS
foreach idx (01 02 03 04 05 06 07 08 09 10 11 12) 
.br
ncks \-F \-d time,,,12 t_anm_8501_8912.nc foo.
.br
ncra foo. t_anm_8589_.nc
.br
end
.RE
Note that 
.B ncra
understands the 
.B stride
argument so the two
commands inside the loop may be combined into the single command 
.RS
ncra \-F \-d time,,,12 t_anm_8501_8912.nc foo.
.RE
Finally, use 
.B ncrcat
to concatenate the 12 average monthly anomaly
files into one twelve-record file which contains the entire seasonal
cycle of the monthly anomalies:
.RS
ncrcat t_anm_8589_??.nc t_anm_8589_0112.nc
.RE

.\" NB: Append man_end.txt here
.\" $Header$ -*-nroff-*-
.\" Purpose: Trailer file for common ending to NCO man pages
.\" Usage: 
.\" Append this file to end of NCO man pages immediately after marker
.\" that says "Append man_end.txt here"
.SH AUTHOR
.B NCO
manual pages written by Charlie Zender and originally formatted by Brian Mays.

.SH "REPORTING BUGS"
Report bugs to <http://sf.net/bugs/?group_id=3331>.

.SH COPYRIGHT
Copyright \(co 1995-present Charlie Zender
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

.SH "SEE ALSO"
The full documentation for
.B NCO
is maintained as a Texinfo manual called the 
.B NCO Users Guide.
Because 
.B NCO
is mathematical in nature, the documentation includes TeX-intensive
portions not viewable on character-based displays. 
Hence the only complete and authoritative versions of the 
.B NCO Users Guide 
are the PDF (recommended), DVI, and Postscript versions at
<http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>,
and <http://nco.sf.net/nco.ps>, respectively.
HTML and XML versions
are available at <http://nco.sf.net/nco.html> and
<http://nco.sf.net/nco.xml>, respectively.

If the
.B info
and
.B NCO
programs are properly installed at your site, the command
.IP
.B info nco
.PP
should give you access to the complete manual, except for the
TeX-intensive portions.

.SH HOMEPAGE
The 
.B NCO
homepage at <http://nco.sf.net> contains more information.
